package cn.iocoder.yudao.module.reading.service.file;

import cn.iocoder.yudao.module.infra.controller.admin.file.vo.file.FilePresignedUrlRespVO;
import cn.iocoder.yudao.module.reading.controller.admin.file.vo.AudioUploadRespVO;
import org.springframework.web.multipart.MultipartFile;

/**
 * 绘本阅读应用文件服务接口
 * 提供业务相关的文件上传和管理功能
 * 
 * @author 李晨
 */
public interface ReadingFileService {

    // =============================================
    // 用户相关文件上传
    // =============================================
    
    /**
     * 上传用户头像
     * 
     * @param userId 用户ID
     * @param avatarFile 头像文件
     * @return 头像文件访问URL
     */
    String uploadUserAvatar(Long userId, MultipartFile avatarFile);
    
    /**
     * 上传用户配音文件
     *
     * @param userId 用户ID
     * @param bookId 绘本ID
     * @param pageId 页面ID
     * @param recordingFile 配音文件
     * @return 配音文件访问URL
     */
    String uploadUserRecording(Long userId, Long bookId, Long pageId, MultipartFile recordingFile);

    // =============================================
    // 绘本相关文件上传
    // =============================================
    
    /**
     * 上传绘本封面
     * 
     * @param bookSetId 绘本集ID
     * @param bookId 绘本ID
     * @param coverFile 封面文件
     * @return 封面文件访问URL
     */
    String uploadBookCover(Long bookSetId, Long bookId, MultipartFile coverFile);
    
    /**
     * 上传绘本页面图片
     * 
     * @param bookSetId 绘本集ID
     * @param bookId 绘本ID
     * @param pageNumber 页码
     * @param pageFile 页面图片文件
     * @return 页面图片文件访问URL
     */
    String uploadBookPage(Long bookSetId, Long bookId, Integer pageNumber, MultipartFile pageFile);
    
    /**
     * 上传绘本音频文件
     * 
     * @param bookSetId 绘本集ID
     * @param bookId 绘本ID
     * @param pageNumber 页码（可选）
     * @param audioFile 音频文件
     * @return 音频文件访问URL
     */
    String uploadBookAudio(Long bookSetId, Long bookId, Integer pageNumber, MultipartFile audioFile);

    // =============================================
    // 绘本集相关文件上传
    // =============================================
    
    /**
     * 上传绘本集封面
     *
     * @param bookSetId 绘本集ID
     * @param coverFile 封面文件
     * @return 封面文件访问URL
     */
    String uploadBookSetCover(Long bookSetId, MultipartFile coverFile);

    /**
     * 上传绘本集封面（支持替换旧文件）
     *
     * @param bookSetId 绘本集ID
     * @param coverFile 封面文件
     * @param oldCoverPath 旧封面路径（如果有）
     * @return 封面文件访问URL
     */
    String uploadBookSetCover(Long bookSetId, MultipartFile coverFile, String oldCoverPath);

    // =============================================
    // 音频资源文件上传
    // =============================================
    
    /**
     * 上传音频资源文件
     *
     * @param category 音频分类
     * @param language 语言类型
     * @param audioFile 音频文件
     * @return 音频上传结果（包含URL、时长等信息）
     */
    AudioUploadRespVO uploadAudioResource(String category, String language, MultipartFile audioFile);
    
    /**
     * 上传音频封面
     * 
     * @param audioId 音频ID
     * @param coverFile 封面文件
     * @return 封面文件访问URL
     */
    String uploadAudioCover(Long audioId, MultipartFile coverFile);

    // =============================================
    // 预签名URL获取（用于前端直传）
    // =============================================
    
    /**
     * 获取用户头像上传预签名URL
     * 
     * @param userId 用户ID
     * @param fileName 文件名
     * @return 预签名URL信息
     */
    FilePresignedUrlRespVO getUserAvatarPresignedUrl(Long userId, String fileName);
    
    /**
     * 获取绘本封面上传预签名URL
     * 
     * @param bookSetId 绘本集ID
     * @param bookId 绘本ID
     * @param fileName 文件名
     * @return 预签名URL信息
     */
    FilePresignedUrlRespVO getBookCoverPresignedUrl(Long bookSetId, Long bookId, String fileName);
    
    /**
     * 获取绘本页面图片上传预签名URL
     * 
     * @param bookSetId 绘本集ID
     * @param bookId 绘本ID
     * @param pageNumber 页码
     * @param fileName 文件名
     * @return 预签名URL信息
     */
    FilePresignedUrlRespVO getBookPagePresignedUrl(Long bookSetId, Long bookId, Integer pageNumber, String fileName);
    
    /**
     * 获取音频文件上传预签名URL
     * 
     * @param category 音频分类
     * @param language 语言类型
     * @param fileName 文件名
     * @return 预签名URL信息
     */
    FilePresignedUrlRespVO getAudioResourcePresignedUrl(String category, String language, String fileName);

    // =============================================
    // 文件删除方法
    // =============================================

    /**
     * 删除绘本集封面文件
     *
     * @param relativePath 相对路径
     * @return 是否删除成功
     */
    boolean deleteBookSetCover(String relativePath);

    /**
     * 删除绘本封面文件
     *
     * @param relativePath 相对路径
     * @return 是否删除成功
     */
    boolean deleteBookCover(String relativePath);

    /**
     * 删除绘本页面图片文件
     *
     * @param relativePath 相对路径
     * @return 是否删除成功
     */
    boolean deleteBookPageImage(String relativePath);

    /**
     * 删除绘本音频文件
     *
     * @param relativePath 相对路径
     * @return 是否删除成功
     */
    boolean deleteBookAudio(String relativePath);

    /**
     * 通用文件删除方法
     *
     * @param relativePath 相对路径
     * @return 是否删除成功
     */
    boolean deleteFile(String relativePath);

    // =============================================
    // 文件验证方法
    // =============================================

    /**
     * 验证图片文件
     *
     * @param file 文件
     * @param maxSize 最大文件大小（字节）
     * @throws IllegalArgumentException 如果文件不符合要求
     */
    void validateImageFile(MultipartFile file, long maxSize);

    /**
     * 验证音频文件
     *
     * @param file 文件
     * @param maxSize 最大文件大小（字节）
     * @throws IllegalArgumentException 如果文件不符合要求
     */
    void validateAudioFile(MultipartFile file, long maxSize);
}
